home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / HyperCard / XFoxEvents tutorial app / XFoxEvents.readme < prev   
Text File  |  1993-09-27  |  13KB  |  387 lines
  1. /* XFoxEvents version 1.4.2, 8-AUG-1993 ©1993 A.D. Software
  2.  
  3. THIS IS NOT FREE - see Shareware Details at end.
  4.  
  5. OVERVIEW
  6. XFoxEvents was previously known as XBrowse2Click and was renamed in the v1.3
  7. release to better indicate the product purpose. It provides event filters for
  8. solving problems with the user-interface of FoxBase+/Mac:
  9. 1) the Browse filter allows you to convert double-clicking or hitting
  10.    the Tab, Enter or Return keys into a command-keystroke of your
  11.    choice (eg: command-O for Open), or a keystroke (ctrl-W= chr(23) ) which    
  12.    will terminate a FOX READ. This enables you to double-click Browse lines  
  13.    and go straight into editing a record.
  14.  
  15. 2) the Return filter simply converts Return characters to Tabs. This is
  16.    useful if you want to have the TAB and RETURN keys jump between fields
  17.    yet still have Enter terminate the READ and have looping back to the 
  18.    top field (ie: using SET STRICT ON). The problem with FoxBase is that
  19.    the Return key is usually treated the same as Enter.
  20.  
  21. 3) the MouseDown filter allows you to convert a SINGLE mouse-click into a 
  22.    command-keystroke or ctrl-W. It has up to 255 optional filter rectangles
  23.    which restricts it to sensing in a given area.
  24.    Version 1.4.1 adds an Invert option to MouseDown which allows you to
  25.    REPLACE FOX BUTTONS! You can then use the UPDATED() function to see if
  26.    any GET's have modified data.
  27.    
  28.    The default is to trap clicks anywhere on the screen, OVERRIDING ANY
  29.    FOX BUTTONS OR FIELDS. You would only use the default case for
  30.    something like an overall picture with no other fields or controls.
  31.    (eg: showing a map).
  32.  
  33.  
  34. DETAILS OF USING THE XFCN
  35.  
  36. THEORY
  37. The XFCN actually installs a separate piece of code for each of the filters,
  38. very much like the "inits" such as PopChar, screensavers etc. Therefore it is
  39. VERY important to Deactivate the current filter when you are finished.
  40.  
  41. The filters are aware when you "change application layers" under MultiFinder
  42. or System 7.
  43.  
  44. WARNING - if you RELEASE the XFCN you will waste a chunk of FoxBase memory. Don't
  45. release the XFCN and then LOAD it - leave it loaded for the life of your program.
  46.  
  47.  
  48. GENERAL USE OF XFCN'S
  49. XFCN's (and XCMDs) live in the current RESOURCE file, either your default
  50. FOXUSER file or a file that you've specified with a SET RESOURCE TO. They are
  51. loaded with the LOAD command (eg: LOAD XFoxEvents FUNCTION). Note that the
  52. FUNCTION keyword is used as shown in this example for any XFCN's (to load an
  53. XCMD you just specify LOAD anXCMD).
  54.  
  55. The difference between XFCN and XCMD is that the XFCN returns a value, much
  56. like a FoxBase UDF.
  57.  
  58. To call an XFCN you issue a CALL command which returns a value to the
  59. specified variable (creating it if doesn't already exist).
  60. eg: CALL XFoxEvents TO res WITH "L"
  61.  
  62. Normally, you can reuse the memory of an XFCN with the RELEASE MODULE itsName
  63. command. However, this should NOT be applied to this XFCN - load it once,
  64. early, and leave it loaded (you don't have to release it if you are quitting
  65. your program as the quitting action cleans up the memory).
  66.  
  67. WARNING
  68. 1) It will cause all kind of weird errors if you LOAD the same XFCN twice
  69.    while running, without doing a RELEASE MODULE of the earlier LOAD.
  70.  
  71. 2) It is VERY important not to RELEASE MODULE this XFCN while a filter is 
  72.    active, as another load of the XFCN wouldn't know about the active filter.
  73.  
  74.  
  75. DETAILS OF USING XFoxEvents
  76. In general, the return value is used to indicate success or the nature of an
  77. error. The first parameter is a "switch" to tell the XFCN which operation to
  78. perform.
  79.  
  80. The following descriptions show a sample usage of each call, with full details 
  81. of any additional parameters and the return value(s).
  82.  
  83.  
  84. LOADING THE FILTERS
  85. This step is performed ONCE for each run of your program or FoxBase (ie: don't
  86. repeat without exiting FoxBase).
  87.  
  88. CALL XFoxEvents TO res WITH "L"
  89.  
  90. RETURN VALUES
  91.   0 = OK
  92.  -1 = invalid function switch
  93.  -2 = couldn't find one of the filters
  94.  
  95.  
  96. ACTIVATING THE BROWSE FILTER
  97.  
  98. PARAMETERS
  99.   1 - "B"
  100.   2 - letter of the command key to send  OR
  101.       "" means send ctrl-W  OR
  102.       chr(27) will send ESC
  103.       
  104.   3 - bitmask of what events are converted to a command-key
  105.        bit              value
  106.         0 = double-click (1)
  107.         1 = Enter key    (2)
  108.         2 = Return key   (4)
  109.         3 = Tab key      (8)
  110. eg: value of 15 = react to all four events
  111.     value of  3 = react to double-click and Enter but NOT Tab or Return
  112.  
  113. CALL XFoxEvents TO res WITH "B", "O", 3
  114.  
  115. RETURN VALUES
  116.   0 = OK
  117.  -1 = invalid function switch
  118.  
  119. NOTE: with the standard Browse windows, there is a title area at the top of the window.
  120. Double-clicks in this area will still be detected - effectively giving you the "feature"
  121. of double-click the titles to open the currently selected record, regardless of it
  122. being out of sight. Nobody's complained about this so far so I left it in.
  123.  
  124.  
  125.  
  126. ACTIVATING THE RETURN FILTER
  127. Every Return keystroke will be converted to a Tab, until you perform a 
  128. Deactivate. Note: this only applies to the plain Return key, pressed
  129. without any modifiers (eg: option-Return, shift-Return). You can therefore use
  130. option-Return within memo fields, the same as you can use option-Tab.
  131.  
  132. PARAMETERS
  133.   1 - "R"
  134.  
  135. eg: CALL XFoxEvents TO res WITH "R"
  136.  
  137. RETURN VALUES
  138.   0 = OK
  139.  -1 = invalid function switch
  140.  
  141.  
  142.  
  143. MOUSEDOWN SUMMARY
  144. The mousedown filter allows you to clear the status flag without
  145. repeating the activate call. You can define one hot rectangle at the
  146. time of activation and follow that call with a number of additional
  147. definition calls to a total of 255 hot rectangles. If you have a hot
  148. rectangle list established, the Activate allows you to retain that list
  149. without redefinition. This will be retained until you exit FoxBase.
  150.  
  151. The filter returns the logical number of the rectangle clicked, to save
  152. you working that out from the position clicked.
  153.  
  154. With the MI call, you can set the filter mode where
  155. the clicked rectangle is highlighted like a button, including the logic
  156. to "slide-off" without releasing the mouse.
  157.  
  158. In the Button Bar mode (MB) clicks in the frontmost window will be
  159. ignored and only clicks in a background window will be processed.
  160. (See the comprehensive example for how this is used in practice).
  161. NOTE all background Fox windows are considered to be button bars and will
  162. accept clicks, regardless of their actual content.
  163.  
  164.  
  165. ACTIVATING THE MOUSEDOWN FILTER
  166.  
  167. PARAMETERS
  168.   1 - "M"  optional 2nd letter E means use Existing rectangles
  169.   2 - letter of the command key to send OR
  170.       "" means send ctrl-W OR
  171.       chr(27) will send ESC
  172. following are optional, defaults to whole window, or existing list
  173.   3 - top
  174.   4 - left
  175.   5 - bottom
  176.   6 - right
  177.  
  178. eg:  for a single line, given a clause in a .FMT like
  179. @ PIXELS 125,7 SAY "Community Serv:" STYLE 65536 FONT "Chicago",12 
  180. you can work out the width and height with
  181. screen 1 font "Chicago",12 top
  182. ?val(sys(1025)) + val(sys(1026)) + val(sys(1027))/3    && height
  183. && as used by Fox in row,col addressing ascent + descent + leading/3
  184. ?sys(1030, "Community Serv:")    && width
  185.  
  186. OR
  187.  
  188. just use the current point size for the height
  189.  
  190. CALL XFoxEvents TO res WITH "M", "", 3, 125,  15, 185
  191.  
  192. RETURN VALUES
  193.   0 = OK
  194.  -1 = invalid function switch
  195.  -4 = not enough parameters (either 2 or all 6 are needed)
  196.  
  197.  
  198. ADDING MORE MOUSEDOWN FILTER HOT RECTANGLES
  199.  
  200. PARAMETERS
  201.   1 - "MR"
  202.   2 - top
  203.   3 - left
  204.   4 - bottom
  205.   5 - right
  206.  
  207. CALL XFoxEvents TO res WITH "MR", 3, 125, 7, 12, 60
  208.  
  209. RETURN VALUES
  210.   0 = OK
  211.  -1 = invalid function switch
  212.  -4 = not enough parameters
  213.  
  214.  
  215. CLEARING THE MOUSEDOWN STATUS FLAG
  216. PARAMETERS
  217.   1 - "MC"
  218.   
  219.   
  220. ENABLING INVERTING OF RECTANGLES 
  221. PARAMETERS
  222.   1 - "MI"
  223.   2 - "+" to enable mode, any other char to disable, default is ON
  224.   
  225.   
  226. ENABLING BUTTON BAR MODE
  227. PARAMETERS
  228.   1 - "MB"
  229.   2 - "+" to enable mode, any other char to disable, default is ON
  230.   
  231.   
  232. GETTING THE MOUSEDOWN POSITION
  233. PARAMETERS
  234.   1 - "MG"
  235. optional
  236.   2 - name of vertical position variable to return
  237.   3 - name of horizontal position variable to return
  238.  
  239. Note: the position is set by the Mousedown filter and a flag is set
  240. to know if the event has been trapped which is cleared implicitly 
  241. when this call is made.
  242.  
  243. CALL XFoxEvents TO res WITH "G", "mouseV", "mouseH"
  244.  
  245. RETURN VALUES
  246.   0 = NOT a mouse-down event since the last activate/clear
  247.   1 or higher = WAS a valid mouse-down, number returned represents
  248.         which of the rectangles was clicked
  249.  -1 = invalid function switch
  250.  -4 = not enough parameters
  251.  
  252.  
  253.  
  254. WARNING    WARNING    WARNING    WARNING    WARNING    WARNING    WARNING
  255.  
  256. DEACTIVATING FILTERS
  257. MUST be carried out before quitting FoxBase. Failure to do so will cause your Mac
  258. to crash. Note: the filters do NOT have to be deactivated before switching context
  259. to another program, under MultiFinder or System 7, provided FoxBase is still running.
  260.  
  261. CALL XFoxEvents TO res WITH "D"
  262.  
  263. RETURN VALUES
  264.   0 = OK
  265.  -1 = invalid function switch
  266.  
  267. WARNING    WARNING    WARNING    WARNING    WARNING    WARNING    WARNING
  268.  
  269.  
  270.                   
  271. ***************************************************************************
  272. V E R S I O N   H I S T O R Y 
  273. 1.0  14-SEP-1992   
  274.     initial public release as XBrowse2Click
  275.  
  276. 1.3  1-FEB-1993
  277.     public release with mouseDown filter
  278.     renamed to XFoxEvents
  279.     
  280.     documentation extended to clarify some points
  281.     
  282.     compiled with Think C 5.0.4 & Think Pascal 4.0.2.
  283.     
  284.     Browse2Click filter restricted to content area of window (a double click
  285.     anywhere would cause exit in original!) and now can generate ctrl-W or
  286.     ESC keystrokes, instead of just command-keys.
  287.     
  288.     MouseDown filter added.
  289.  
  290. 1.4  7-MAY-1993
  291.     Released to celebrate my 30th birthday!
  292.  
  293.     Content area checking for Browse2Click and MouseDown filters bugs fixed
  294.     and conflict with Now Menus resolved.
  295.     
  296.     See extra notes on Browse2Click function.
  297.  
  298. 1.4.1 3-AUG-1993 (not an official release)
  299.     Mousedown enhancements:
  300.     - return value is now 1 or higher, giving you the number of the rectangle
  301.       to save having to work it out from the position clicked
  302.     - MI call added to enable (or then disable) "Invert" mode which inverts
  303.       the rectangles as if they were buttons.
  304.  
  305. 1.4.2  8-AUG-1993
  306.     Mousedown enhancements:
  307.     - "MI" call given secon param, rather than acting as a toggle on/off
  308.     - "MB" call added to give Button Bar effect
  309.     - clicks in other windows ignored (except when in Button Bar mode)
  310.     - Rectangle documentation error corrected (I use top,left,bot,right)
  311.     
  312.     General Enhancements:
  313.     - now able to use more than one filter together, so double-click and Mousedown
  314.       (Button Bar) can be used on Browse
  315.     - comprehensive demo written
  316.  
  317. 1.4.3  28-AUG-1993
  318.     Mousedown bugfix:
  319.     - the MI call suppressed clicks elsewhere in the window.
  320.     
  321.     Recompiled all filters with Think C v6.0.1
  322.     
  323.  
  324. FUTURE PLANS (depending on demand and YOUR feedback)
  325. Combine the Browse2Click and MouseDown functions into one, so single or double
  326. clicks can be detected, and drag-n-drop can be performed from specified areas to
  327. others.
  328. ***************************************************************************
  329.  
  330.  
  331.  
  332. SHAREWARE DETAILS
  333. Godfather Holdings Pty Ltd as trustee for 
  334. The Dent Family Trust
  335. Trading as A.D. Software
  336. Australian Company Number    009 453 007
  337.  
  338. Contact: Andy Dent BSc, MACS
  339. 94 Bermuda Drive, Ballajura  Western Australia 6066
  340. Phone/Fax:        (09) 249 2719
  341. International:    61 9 249 2719
  342. CompuServe:     100033, 3241
  343. Internet:        dent@dialix.oz.au
  344.  
  345. PAYMENT VIA (decreasing preference)
  346. CompuServe SWREG (check the library summary for the SWREG number)
  347. Australian dollars cash
  348. Australian bank or personal cheques (made out to A.D. Software)
  349. International Money Orders
  350. Visa, Mastercard or Australian Bankcard
  351.  
  352. FEE & UPDATE DETAILS
  353. The fee is $50 Australian (due to our rotten exchange rate
  354.                            this is about $36 US).
  355. Registered users will receive free upgrades with notices mailed
  356. (electronically where possible) of new versions being uploaded, 
  357. and available on disk for a nominal shipping fee, on request.
  358.  
  359.  
  360. OTHER FOXBASE XCMDS
  361. XScrollList Provides loading, filing & display of "arrays" in normal
  362. Mac dialogs with usual list handling facilities supporting arrow keys,
  363. type first few letters to jump to an entry etc.
  364.  
  365. Arrays stored outside of Fox 64kb memory limit and loaded many times
  366. faster than is possible with arrays inside Fox. 
  367. Dialog returns list entry number, record number (optional) and text
  368. of entry selected.
  369.  
  370. Dialogs are constructed as resources (using Apple's ResEdit) and can have as
  371. many buttons as you like, the name of the button pressed being returned to a
  372. Fox variable.
  373.  
  374. Multiple selections are also supported, using the standard technique of
  375. shift-click to select a contiguous range or command-click for ad-hoc items.
  376.  
  377.  
  378. XGetDepth - returns the pixel depth (ie 2, 4, 8, 16 or 32) of the screen (freebie)
  379.  
  380.  
  381. OTHER PRODUCTS & SERVICES
  382. A.D. Software is a custom software development house — if you have any other
  383. XCMD or other programming requirements, please contact me for further information.
  384.  
  385. Major products include a FORTRAN->Pascal translator and multi-user classified
  386. advertisement publishing system.
  387. ---------------------------------------------------------------------------------*/